---
title: Breakpoints
---

import Seo from '../../../components/Seo.astro'
import Badge from '../../../components/Badge.astro'

<Seo
    seo={{
        title: 'Breakpoints',
        description: 'How to use breakpoints with react-native-unistyles'
    }}
>

<Badge label="All platforms" />
<Badge label="2.0.0" />

Breakpoints are user-defined key/value pairs that describe the boundaries of screen sizes.
There's no limit to the number of breakpoints; you can define as many as you want.

### Register breakpoints

To register your breakpoints, create an object with **any** keys:

```tsx
// breakpoints.ts
export const breakpoints = {
    xs: 0,
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200,
    superLarge: 2000,
    tvLike: 4000
} as const
```

The first breakpoint **must** start with `0`. This is required to simulate CSS cascading, e.g., everything below 576px (`sm` breakoint)
will resolve to `xs` breakpoint.

:::danger
If you try to register a breakpoint that doesn't start with 0, Unistyles will throw an error:

"You are trying to register breakpoints that don't start from 0"
:::

If you use TypeScript you need to override the library's type:

```tsx /name/
import { breakpoints } from './breakpoints'

type AppBreakpoints = typeof breakpoints

declare module 'react-native-unistyles' {
  export interface UnistylesBreakpoints extends AppBreakpoints {}
}
```

Finally, to register the breakpoints, call `UnistylesRegistry`:

```tsx /addBreakpoints/
import { UnistylesRegistry } from 'react-native-unistyles'
import { breakpoints } from './breakpoints'

UnistylesRegistry
    .addBreakpoints(breakpoints)
```

To learn more follow setup [guide](/start/setup/).

### How to use breakpoints?

Any style can change based on breakpoints. To do this, change a `value` to an `object`:

```diff lang="tsx" /xs/ /sm/ del="backgroundColor: theme.colors.background" ins="backgroundColor: {"
const stylesheet = createStyleSheet(theme => ({
    container: {
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: theme.colors.background,
        backgroundColor: {
+            // your breakpoints
+            xs: theme.colors.background,
+            sm: theme.colors.barbie
+        }
    },
    text: {
        color: theme.colors.typography
    }
}))
```

You can even use it with nested objects like `transform` or `shadowOffset`:

```ts /xs/ /sm/ /xl/
const stylesheet = createStyleSheet(theme => ({
    container: {
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: {
            xs: theme.colors.background,
            sm: theme.colors.barbie
        },
        transform: [
            {
                translateX: 100
            },
            {
                scale: {
                    xs: 1.5,
                    xl: 0.9
                }
            }
        ]
    }
}))
```

Breakpoints are also avilable with [variants](/reference/variants/).


### Built-in breakpoints `landscape` and `portrait`

Even if you don't use custom breakpoints, you can still utilize Unistyles' predefined breakpoints available on mobile devices: `portrait` and `landscape`.

- `portrait` will resolve to your device's width in portrait mode
- `landscape` will resolve to your device's width in landscape mode

:::tip
These breakpoints are only available on mobile unless you register your own.
:::

```ts /landscape/ /portrait/
const stylesheet = createStyleSheet(theme => ({
    container: {
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: {
            landscape: theme.colors.background,
            portrait: theme.colors.barbie
        }
    }
}))
```

### Access the current breakpoint

You can access the current breakpoint with the `useStyles` hook:

```tsx
const { breakpoint } = useStyles(stylesheet)
```

or with `UnistylesRuntime`:

```tsx /UnistylesRuntime.breakpoint/
import { UnistylesRuntime } from 'react-native-unistyles'

// check the current breakpoint
export const CurrentBreakpoint = () => (
    <Text>
        Current breakpoint is {UnistylesRuntime.breakpoint}
    </Text>
)
```

### Get registered breakpoints

Access your registered breakpoints object with `UnsitylesRuntime`:

```tsx /UnistylesRuntime.breakpoints/
import { UnistylesRuntime } from 'react-native-unistyles'

// check the registered breakpoints
export const RegisteredBreakpoints = () => (
    <Text>
        My registered breakpoint are {JSON.stringify(UnistylesRuntime.breakpoints)}
    </Text>
)
```

:::tip[UnistylesRuntime]
UnistylesRuntime is a powerful feature, and you can learn more about it [here](/reference/unistyles-runtime).
:::

</Seo>
